<!DOCTYPE HTML>
<html lang="en">
<head>
<title>Hotstring() - Syntax &amp; Usage | AutoHotkey</title>
<meta name="description" content="The Hotstring function creates, modifies, enables, or disables a hotstring while the script is running." />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>Hotstring() <span class="ver">[v1.1.28+]</span></h1>

<p>Creates, modifies, enables, or disables a <a href="../Hotstrings.htm">hotstring</a> while the script is running.</p>

<pre class="Syntax">
<span class="func">Hotstring</span>(String <span class="optional">, Replacement, OnOffToggle</span>)
<span class="func">Hotstring</span>(<a href="#NewOptions">NewOptions</a>)
OldValue := <span class="func">Hotstring</span>("<a href="#EndChars">EndChars</a>" <span class="optional">, NewValue</span>)
OldValue := <span class="func">Hotstring</span>("<a href="#MouseReset">MouseReset</a>" <span class="optional">, NewValue</span>)
<span class="func">Hotstring</span>("Reset")
</pre>
<h2>Parameters</h2>
<dl>

  <dt>String</dt>
  <dd>
    <p>The hotstring's trigger string, preceded by <a href="../Hotstrings.htm">the usual colons</a> and <a href="../Hotstrings.htm#Options">option characters</a>. For example, <code>"::btw"</code> or <code>":*:]d"</code>.</p>
    <p><em>String</em> may be matched to an existing hotstring by considering <a href="../Hotstrings.htm#C">case-sensitivity (C)</a>, <a href="../Hotstrings.htm#Question">word-sensitivity (?)</a>, activation criteria (as set by <a href="_If.htm">#If</a>, <a href="_IfWinActive.htm">#IfWin</a> or <a href="Hotkey.htm#IfWin">Hotkey, If</a>) and the trigger string. For example, <code>"::btw"</code> and <code>"::BTW"</code> match unless the case-sensitive mode was enabled as a default, while <code>":C:btw"</code> and <code>":C:BTW"</code> never match. The <code>C</code> and <code>?</code> options may be included in <em>String</em> or set as defaults by the <a href="_Hotstring.htm">#Hotstring</a> directive or a previous call to <a href="#NewOptions">this function</a>.</p>
    <p>If the hotstring already exists, any options specified in <em>String</em> are put into effect, while all other options are left as is. However, since hotstrings with <code>C</code> or <code>?</code> are considered distinct from other hotstrings, it is not possible to add or remove these options. Instead, turn off the existing hotstring and create a new one.</p>
    <p>When a hotstring is first created -- either by the Hotstring function or a <a href="../Hotstrings.htm">double-colon label</a> in the script -- its trigger string and sequence of option characters becomes the permanent name of that hotstring as reflected by <a href="../Variables.htm#ThisHotkey">A_ThisHotkey</a>. This name does not change even if the Hotstring function later accesses the hotstring with different option characters.</p>
    <p>If the <a href="../Hotstrings.htm#X">X (execute) option</a> is present in <em>String</em> (not just set as a default), the <em>Replacement</em> parameter is interpreted as a label or function name instead of replacement text. This has no effect if <em>Replacement</em> is an object.</p>
  </dd>

  <dt>Replacement</dt>
  <dd>
    <p>The replacement string, or a <a href="../misc/Labels.htm">label</a>, <a href="../Functions.htm">function</a> or <a href="../objects/Functor.htm">function object</a> to call (as a new <a href="../misc/Threads.htm">thread</a>) when the hotstring triggers.</p>
    <p>By default, all strings are treated as replacement text. To specify a label or function by name, include the <a href="../Hotstrings.htm#X">X (execute)</a> option in <em>String</em>. Both normal labels and <a href="../Hotkeys.htm">hotkey</a>/<a href="../Hotstrings.htm">hotstring</a> labels can be used, and the trailing colon(s) should not be included. If a function and a label exist with the same name, the label takes precedence. To use the function instead, pass a <a href="../objects/Func.htm">function reference</a>.</p>
    <p>This parameter can be left blank if the hotstring already exists, in which case its replacement will not be changed. This is useful to change only the hotstring's options, or to turn it on or off.</p>
    <p class="note"><strong>Note</strong>: If this parameter is specified but the hotstring is disabled from a previous use of this function, the hotstring will remain disabled. To prevent this, include the word <code>"On"</code> in <em>OnOffToggle</em>.</p>
  </dd>

  <dt>OnOffToggle</dt>
  <dd>
    <p>One of the following strings (enclosed in quote marks if used literally):</p>
    <p><strong>On</strong>: Enables the hotstring.</p>
    <p><strong>Off</strong>: Disables the hotstring.</p>
    <p><strong>Toggle</strong>: Sets the hotstring to the opposite state (enabled or disabled).</p>
    <p><span class="ver">[v1.1.30+]:</span> The values 1 (or <code>true</code>), 0 (or <code>false</code>) and -1 may be used in place of On, Off and Toggle, respectively.</p>
  </dd>

</dl>

<h2 id="Errors">Errors</h2>
<p>This function throws an exception if the parameters are invalid or a memory allocation fails. It does not affect <a href="../misc/ErrorLevel.htm">ErrorLevel</a>.</p>
<p>An exception is also thrown if <em>Replacement</em> is omitted and <em>String</em> is valid but does not match an existing hotstring. This can be utilized to test for the existence of a hotstring. For example:</p>
<pre>try
    Hotstring("::btw")
catch
    MsgBox The hotstring does not exist or it has no variant for the current IfWin criteria.</pre>

<h2>Remarks</h2>
<p>The <a href="Hotkey.htm#IfWin">current IfWin setting</a> determines the <a href="#variant">variant</a> of a hotstring upon which the Hotstring function will operate.</p>
<p>A given label or function can be the target of more than one hotstring. If it is known that a label or function was called by a hotstring, you can determine which hotstring by checking the built-in variable <a href="../Variables.htm#ThisHotkey">A_ThisHotkey</a>.</p>
<p>If the script is <a href="Suspend.htm">suspended</a>, newly added/enabled hotstrings will also be suspended until the suspension is turned off (unless they are exempt as described in the <a href="Suspend.htm">Suspend</a> section).</p>
<p>The <a href="_InstallKeybdHook.htm">keyboard</a> and/or <a href="_InstallMouseHook.htm">mouse</a> hooks will be installed or removed if justified by the changes made by this function.</p>
<p>This function cannot directly enable or disable hotstrings in scripts other than its own.</p>
<p>Once a script has at least one hotstring, it becomes persistent, meaning that <a href="ExitApp.htm">ExitApp</a> rather than Exit should be used to terminate it. Hotstring scripts are also automatically <a href="_SingleInstance.htm">#SingleInstance</a> unless <code>#SingleInstance Off</code> has been specified.</p>

<h2 id="variant">Variant (Duplicate) Hotstrings</h2>
<p>A particular hotstring can be created more than once if each definition has different <a href="Hotkey.htm#IfWin">IfWin</a> criteria, <a href="../Hotstrings.htm#C">case-sensitivity</a> (<code>C</code> vs. <code>C0</code>/<code>C1</code>), or <a href="../Hotstrings.htm#Question">word-sensitivity</a> (<code>?</code>). These are known as <em>hotstring variants</em>. For example:</p>
<pre>Hotkey, IfWinActive, ahk_group CarForums
Hotstring("::btw", "behind the wheel")
Hotkey, IfWinActive, Inter-Office Chat
Hotstring("::btw", "back to work")
Hotkey, IfWinActive
Hotstring("::btw", "by the way")</pre>
<p>If more than one variant of a hotstring is eligible to fire, only the one created earliest will fire.</p>
<p>For more information about IfWin, see <a href="_IfWinActive.htm#gen">#IfWin's General Remarks</a>.</p>

<h2 id="EndChars">EndChars</h2>
<pre class="Syntax">OldValue := <span class="func">Hotstring</span>("EndChars" <span class="optional">, NewValue</span>)</pre>
<p>Retrieves or modifies the set of characters used as <a href="../Hotstrings.htm#EndChars">ending characters</a> by the hotstring recognizer. For example:</p>
<pre>prev_chars := Hotstring("EndChars", "-()[]{}':;""/\,.?!`n `t")
MsgBox The previous value was: %prev_chars%</pre>
<p><a href="Hotstring.htm#EndChars">#Hotstring EndChars</a> also affects this setting.</p>
<p>It is currently not possible to specify a different set of end characters for each hotstring.</p>

<h2 id="MouseReset">MouseReset</h2>
<pre class="Syntax">OldValue := <span class="func">Hotstring</span>("MouseReset" <span class="optional">, NewValue</span>)</pre>
<p>Retrieves or modifies the global setting which controls whether mouse clicks reset the hotstring recognizer, as described <a href="../Hotstrings.htm#NoMouse">here</a>. <em>NewValue</em> should be 1 (true) to enable mouse click detection and resetting of the hotstring recognizer, or 0 (false) to disable it. The return value is the setting which was in effect before the function was called.</p>
<p>The <a href="_InstallMouseHook.htm">mouse</a> hook may be installed or removed if justified by the changes made by this function.</p>
<p><a href="_Hotstring.htm">#Hotstring NoMouse</a> also affects this setting, and is equivalent to specifying <code>false</code> for <em>NewValue</em>.</p>

<h2 id="Reset">Reset <span class="ver">[v1.1.28.01+]</span></h2>
<pre class="Syntax"><span class="func">Hotstring</span>("Reset")</pre>
<p>Immediately resets the hotstring recognizer. In other words, the script will begin waiting for an entirely new hotstring, eliminating from consideration anything you previously typed.</p>

<h2 id="NewOptions">Setting Default Options</h2>
<pre class="Syntax"><span class="func">Hotstring</span>(NewOptions)</pre>
<p>To set new default options for subsequently created hotstrings, pass the options to the Hotstring function without any leading or trailing colon. For example: <code>Hotstring("T")</code>.</p>
<p>Turning on <a href="../Hotstrings.htm#C">case-sensitivity (C)</a> or <a href="../Hotstrings.htm#Question">word-sensitivity (?)</a> also affects which existing hotstrings will be found by any subsequent calls to the Hotstring function. For example, <code>Hotstring(":T:btw")</code> will find <code>::BTW</code> by default, but not if <code>Hotstring("C")</code> or <code><a href="_Hotstring.htm">#Hotstring</a> C</code> is in effect. This can be undone or overridden by passing a mutually-exclusive option; for example, <code>C0</code> and <code>C1</code> override <code>C</code>.</p>

<h2>Related</h2>
<p><a href="../Hotstrings.htm">Hotstrings</a>, <a href="_IfWinActive.htm">#IfWinActive/Exist</a>, <a href="_MaxThreadsPerHotkey.htm">#MaxThreadsPerHotkey</a>, <a href="Suspend.htm">Suspend</a>, <a href="../misc/Threads.htm">Threads</a>, <a href="Thread.htm">Thread</a>, <a href="Critical.htm">Critical</a></p>

<h2>Examples</h2>

<div class="ex" id="ExHelper">
<p><a href="#ExHelper">#1</a>: Hotstring Helper. The following script might be useful if you are a heavy user of hotstrings. It's based on <a href="../Hotstrings.htm#Helper">the script created by Andreas Borutta</a>. By pressing <kbd>Win</kbd>+<kbd>H</kbd> (or another hotkey of your choice), the currently selected text can be turned into a hotstring.  For example, if you have &quot;by the way&quot; selected in a word processor, pressing <kbd>Win</kbd>+<kbd>H</kbd> will prompt you for its abbreviation (e.g. btw) and then add the new hotstring to the script. The hotstring will be activated without reloading the script.</p>
<pre>#h::  <em>; Win+H hotkey
; Get the text currently selected. The clipboard is used instead of
; "ControlGet Selected" because it works in a greater variety of editors
; (namely word processors).  Save the current clipboard contents to be
; restored later. Although this handles only plain text, it seems better
; than nothing:</em>
ClipboardOld := Clipboard
Clipboard := "" <em>; Must start off blank for detection to work.</em>
Send ^c
ClipWait 1
if ErrorLevel  <em>; ClipWait timed out.</em>
    return
<em>; Replace CRLF and/or LF with `n for use in a "send-raw" hotstring:
; The same is done for any other characters that might otherwise
; be a problem in raw mode:</em>
ClipContent := StrReplace(Clipboard, "``", "````")  <em>; Do this replacement first to avoid interfering with the others below.</em>
ClipContent := StrReplace(ClipContent, "`r`n", "``r")  <em>; Using `r works better than `n in MS Word, etc.</em>
ClipContent := StrReplace(ClipContent, "`n", "``r")
ClipContent := StrReplace(ClipContent, "`t", "``t")
ClipContent := StrReplace(ClipContent, "`;", "```;")
Clipboard := ClipboardOld  <em>; Restore previous contents of clipboard.</em>
ShowInputBox(":T:`::" ClipContent)
return

ShowInputBox(DefaultValue)
{
    <em>; This will move the InputBox's caret to a more friendly position:</em>
    SetTimer, MoveCaret, 10
    <em>; Show the InputBox, providing the default hotstring:</em>
    InputBox, UserInput, New Hotstring,
    (
    Type your abreviation at the indicated insertion point. You can also edit the replacement text if you wish.

    Example entry: :R:btw`::by the way
    ),,,,,,,, %DefaultValue%
    if ErrorLevel  <em>; The user pressed Cancel.</em>
        return

    if RegExMatch(UserInput, "O)(?P&lt;Label&gt;:.*?:(?P&lt;Abbreviation&gt;.*?))::(?P&lt;Replacement&gt;.*)", Hotstring)
    {
        if !Hotstring.Abbreviation
            MsgText := "You didn't provide an abbreviation"
        else if !Hotstring.Replacement
            MsgText := "You didn't provide a replacement"
        else
        {
            Hotstring(Hotstring.Label, Hotstring.Replacement)  <em>; Enable the hotstring now.</em>
            FileAppend, `n%UserInput%, %A_ScriptFullPath%  <em>; Save the hotstring for later use.</em>
        }
    }
    else
        MsgText := "The hotstring appears to be improperly formatted"

    if MsgText
    {
        MsgBox, 4,, %MsgText%. Would you like to try again?
        IfMsgBox, Yes
            ShowInputBox(DefaultValue)
    }
    return
    
    MoveCaret:
    WinWait, New Hotstring
    <em>; Otherwise, move the InputBox's insertion point to where the user will type the abbreviation.</em>
    Send {Home}{Right 3}
    SetTimer,, Off
    return
}</pre>
</div>

</body>
</html>
